listmodels: Clarify documentation for function prototypes

Fixes #1341

diff --git a/gtk/gtkfilterlistmodel.h b/gtk/gtkfilterlistmodel.h
index 3ab1601ff57fe42daeaa448ef81278a314d619f8..e1f256ac2df7c7c7bc049a862197fd7b2066e367 100644 (file)
--- a/gtk/gtkfilterlistmodel.h
+++ b/gtk/gtkfilterlistmodel.h
@@ -36,6 +36,17 @@ G_BEGIN_DECLS
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_FINAL_TYPE (GtkFilterListModel, gtk_filter_list_model, GTK, FILTER_LIST_MODEL, GObject)
 
+/**
+ * GtkFilterListModelFilterFunc:
+ * @item: (type GObject): The item that may be filtered
+ * @user_data: user data
+ *
+ * User function that is called to determine if the @item of the original model should be visible.
+ * If it should be visible, this function must return %TRUE. If the model should filter out the
+ * @item, %FALSE must be returned.
+ *
+ * Returns: %TRUE to keep the item around
+ */
 typedef gboolean (* GtkFilterListModelFilterFunc) (gpointer item, gpointer user_data);
 
 GDK_AVAILABLE_IN_ALL

diff --git a/gtk/gtkmaplistmodel.c b/gtk/gtkmaplistmodel.c
index 6a3de78f8bcb1cf6e20a8e8d3dc366a0613acfce..6f5e331d80738ba75025d6800d5fb3d464ce6627 100644 (file)
--- a/gtk/gtkmaplistmodel.c
+++ b/gtk/gtkmaplistmodel.c
@@ -180,6 +180,11 @@ gtk_map_list_model_get_item (GListModel *list,
     }
 
   node->item = self->map_func (g_list_model_get_item (self->model, position), self->user_data);
+  if (!G_TYPE_CHECK_INSTANCE_TYPE (node->item, self->item_type))
+    {
+      g_critical ("Map function returned a %s, but it is not a subtype of the model's type %s",
+                  G_OBJECT_TYPE_NAME (node->item), g_type_name (self->item_type));
+    }
   g_object_add_weak_pointer (node->item, &node->item);
 
   return node->item;

diff --git a/gtk/gtkmaplistmodel.h b/gtk/gtkmaplistmodel.h
index e5c637297a844b8727b971ba3bed2d41998503c1..f0ddcc95249a2a6f9c1b3af45c9fd1fe2f7bbb6e 100644 (file)
--- a/gtk/gtkmaplistmodel.h
+++ b/gtk/gtkmaplistmodel.h
@@ -38,12 +38,17 @@ G_DECLARE_FINAL_TYPE (GtkMapListModel, gtk_map_list_model, GTK, MAP_LIST_MODEL,
 
 /**
  * GtkMapListModelMapFunc:
- * @item: (transfer full): The item to map
+ * @item: (type GObject) (transfer full): The item to map
  * @user_data: user data
  *
- * User function that is called to map an @item of the original model.
+ * User function that is called to map an @item of the original model to
+ * an item expected by the map model.
  *
- * Returns: (transfer full): The item to map to. This function may not return %NULL
+ * The returned items must conform to the item type of the model they are
+ * used with.
+ *
+ * Returns: (type GObject) (transfer full): The item to map to.
+ *     This function may not return %NULL
  */
 typedef gpointer (* GtkMapListModelMapFunc) (gpointer item, gpointer user_data);
 

diff --git a/gtk/gtktreelistmodel.h b/gtk/gtktreelistmodel.h
index fd9585e2be7079f25e30e3065760921803715392..40c4d572622b9185625cc162099dbb3ff3286b57 100644 (file)
--- a/gtk/gtktreelistmodel.h
+++ b/gtk/gtktreelistmodel.h
@@ -41,11 +41,19 @@ G_DECLARE_FINAL_TYPE (GtkTreeListRow, gtk_tree_list_row, GTK, TREE_LIST_ROW, GOb
 
 /**
  * GtkTreeListModelCreateModelFunc:
- * @item: The item that is expaned
+ * @item: (type GObject): The item that is being expanded
  * @user_data: User data passed when registering the function
  *
  * Prototype of the function called to create new child models when
  * gtk_tree_list_row_set_expanded() is called.
+ *
+ * This function can return %NULL to indicate that @item is guaranteed to be
+ * a leave node and will never have children.  
+ * If it does not have children but may get children later, it should return
+ * an empty model that is filled once children arrive.
+ *
+ * Returns: (nullable): The model tracking the children of @item or %NULL if
+ *     @item can never have children
  */
 typedef GListModel * (* GtkTreeListModelCreateModelFunc) (gpointer item, gpointer user_data);